Why

Clerk initialization blocks on the /client API response, which is a full server roundtrip (500ms-2s). For returning users, this means a loading spinner on every page load even though we already have their session data from the previous visit. Auth providers are infrastructure, and infrastructure that initializes faster wins.

What

Adds an opt-in experimental.swr flag to Clerk.load() that enables stale-while-revalidate initialization. When enabled, clerk-js:

1. Reads a cached Client snapshot from localStorage (saved on previous successful /client response)
2. Checks if the __session cookie JWT is still valid
   • Valid (SSR apps always have one from middleware refresh, CSR within ~60s): emit ready instantly, zero network
   • Expired: call getToken() (edge-routed, fast) to validate session liveness
3. Emits ready/degraded with cached data while /client fetches in the background
4. Silently swaps to fresh /client data when it arrives

The cache is scoped by publishable key, versioned for schema safety, strips JWTs and signIn/signUp flow state before saving, and clears on sign-out (including cross-tab via BroadcastChannel).

Key design decisions

• Token validation gate: never boots with an unvalidated session. Either the cookie JWT is fresh, or getToken confirms liveness.
• 4xx from getToken = session revoked, cache discarded, falls through to normal flow
• Transient errors (5xx/network) = emit degraded with cached data, same as existing degraded behavior
• Cached environment is restored from localStorage before emitting ready so components have valid displayConfig/authConfig
• Session fallback on background /client swap is scoped to SWR context only, doesn't change updateClient behavior for other callers
• Cache save uses updatedAt dedup guard to avoid redundant localStorage writes

Test plan

• 10 unit tests for SWR cache module (save/read/clear/sanitization/token expiry)
• 8 unit tests for SWR init branch (disabled, no cache, valid JWT, expired+getToken, 401, transient error, corrupted cache, session fallback)
• 3 integration tests (cache on reload, clear on sign-out, revoked session fallback)
• 100 existing clerk.test.ts tests still passing
• Manual test: enable experimental: { swr: true }, sign in, reload, verify instant load

🤖 Generated with Claude Code